r? @JohnTitor

rustbot has assigned @JohnTitor.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

@rustbot label +I-libs-api-nominated
@rust-lang/libs-api & @nia-e (not sure if the team ping works so hedging my bets)

Error: relabel handler unexpectedly failed in this comment: failed to add labels to the issue

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #triagebot on Zulip.

CI failure caused by a doc(hidden) trait implementation not having a stability attribute becoming an error once the core::io module was marked stable. I'm not sure why it was ok before and not ok now, but I've added the relevant unstable attribute anyway.

This PR was rebased onto a different main commit. Here's a range-diff highlighting what actually changed.

Rebasing is a normal part of keeping PRs up to date, so no action is needed—this note is just to help reviewers.

r? nia-e

@nia-e is there anything I should do to get a FCP started for this stabilization PR? Also apologies for the ping!

oh, it should have been started! grr. well thankfully i can do it now.

@rfcbot fcp merge libs

@nia-e has proposed to merge this. The next step is review by the rest of the tagged team members:

• @Amanieu
• @BurntSushi
• @cuviper
• @dtolnay
• @joshtriplett
• @the8472
• @thomcc

No concerns currently listed.

Once a majority of reviewers approve (and at most 2 approvals are outstanding), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

To be honest, I still feel uneasy about providing a centralised and opinionated core::io::Error. I had a go at analysing the design of all crates in the list provided in the stabilisation report:

• embedded_io makes the error type an associated type bounded by an Error trait that allows categorising the error into an ErrorKind. read_exact returns a WriteExactError wrapper over the error adding a variant for UnexpectedEof.
• ciborium_io has an associated Error type in both Read and Write which can be set to any type. There's only read_exact and write_all, so there's no need for separate UnexpectedEof handling.
• bitcoin_io provides a central Error type which has a similar API to std's, but without functions to deal with raw error value from the OS.
• no_std_io provides a central Error type with a similar, but slightly more restricted API.
• corez's Error is basically a carbon-copy of std::io::Error.
• axio's Error is akin to std::io::ErrorKind, but with guaranteed represenation.
• ax-io's IoError is an ErrorKind-like enum, too.
• genio has an associated, unbounded Error associated type on both Read and Write. read_exact returns a WriteExactError wrapper like with embedded_io.
• core_io is a literal carbon-copy of std::io.
• acid_io has its own Error type which is restricted to wrapping ErrorKind.
• hadris_io has an associated Error type on Read and Write, bounded by an Error trait that allows categorising errors into ErrorKinds. read_exact returns an Error struct that adds another variant consisting of a string description and an ErrorKind.
• core2 was yanked.
• core3 mirrors std.

While there are certainly some crates which could trivially switch over to core::io::Error, I do not think core::io::Error can e.g. supersede crates like the very popular embedded_io that generalise errors using an associated type. I think the different designs are evidence of at least three very distinct user stories:

• no_std libraries that run under an existing OS want a nice wrapper for OS error codes. E.g. getrandom currently uses its own error type as a thin wrapper over the OS errors. For these, core::io::Error doesn't really work without from_raw_os_error being in core, too.
• Embedded systems want an error type that is informative and doesn't allocate. For these crates, core::io::Error is okay, but fails the allocation criterion. Raw OS errors don't exist, so those code paths are unnecessary. A struct with fields for both an error kind and a message would be better.
• Operating system kernels have their own error codes (those might not fit RawOsError, we shouldn't force people to use i32 in their OS) and want to pass those to userspace. core::io::Error isn't a good design since it encodes more variants that would need to be converted to an error code. E.g. here's @mkroening, a maintainer of Hermit, describing this problem. I imagine the situation is similar for the Rust for Linux people, I don't think they'd want to replace their error type with core::io::Error.

I think the current Error design is suboptimal in all these cases, and hence I fear that we'll just establish another standard here without superseding the existing ones (https://xkcd.com/927/).

I cannot help but think an associated type design, like in embedded_io, is the only one that could work in all these usecases since it allows for the most flexibility. That said, the existing concerns about the complexity of such a design are definitely justified.

To make this concern somewhat actionable, I think the best way forward here would be to solicit more feedback from all the relevant parties (especially the embedded and kernel people, since those are the main audience for no_std).

@rfcbot concern solicit-feedback

no_std libraries that run under an existing OS want a nice wrapper for OS error codes. E.g. getrandom currently uses its own error type as a thin wrapper over the OS errors. For these, core::io::Error doesn't really work without from_raw_os_error being in core, too.

There is a plan to enable this functionality once default EII is supported. I would also argue there are potential-no_std libraries which do not directly interface with error type at all. image for example accepts readers and writers so it only emits whatever errors they produce. An associated error type would work for those crates, but so would core::io::Error. What really matters is that the traits themselves become available, which this enables.

I would also argue that even if embedded_io continued to use their own associated error type, they may want to change how it works based on the availability of core::io::Error. I could easily imagine changing the bound to be core::error::Error + Into<core::io::Error> to allow nicer interop with the rest of the crate ecosystem.

Embedded systems want an error type that is informative and doesn't allocate. For these crates, core::io::Error is okay, but fails the allocation criterion. Raw OS errors don't exist, so those code paths are unnecessary. A struct with fields for both an error kind and a message would be better.

To be clear, core::io::Error does not allocate under any circumstance. Only with alloc::io::Error (not proposed for stabilization in this PR) can (and by extension std::io::Error.

To the latter point, I'd say #133448 addresses that exact design perfectly while also maintaining the standardized type for a cohesive IO ecosystem. const_error is also perfectly compatible with core::io::Error, so this would be functionality instantly available once that feature is stable.

Operating system kernels have their own error codes (those might not fit RawOsError, we shouldn't force people to use i32 in their OS) and want to pass those to userspace. core::io::Error isn't a good design since it encodes more variants that would need to be converted to an error code. E.g. here's @mkroening, a maintainer of Hermit, describing this problem. I imagine the situation is similar for the Rust for Linux people, I don't think they'd want to replace their error type with core::io::Error.

The definition of RawOsError is a separate unstable feature that I don't think needs to be litigated here (in my opinion). Having said that, personally, I think i32 (more specifically c_int which we've adjusted RawOsError to align with for 16 bit platforms) is a very strong default for error codes across systems programming that I think we'd need some concrete examples of that choice limiting code. Demonstrably, every OS kernel supported by Rust's standard library is capable of using the current definition of RawOsError.